home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / Freeware / ttengine-4.3 / Developer / autodocs / ttengine.doc
Encoding:
Text File  |  2002-10-27  |  23.9 KB  |  640 lines
  1. TABLE OF CONTENTS
  2.  
  3. ttrender.library/background
  4. ttrender.library/font_database
  5. ttrender.library/TT_CloseFont
  6. ttrender.library/TT_GetAttrsA
  7. ttrender.library/TT_OpenFontA
  8. ttrender.library/TT_SetAttrsA
  9. ttrender.library/TT_SetFont
  10. ttrender.library/TT_Text
  11. ttrender.library/TT_TextExtent
  12. ttrender.library/TT_TextFit
  13. ttrender.library/TT_TextLength
  14. ttrender.library/background                       ttrender.library/background
  15.  
  16.  
  17.    PURPOSE
  18.  
  19.    The library is fast, AmigaOS friendly TrueType render engine. It has
  20.    nothing to do with Amiga outline font system. This system has a lot of
  21.    limitations which make it useless for high speed and quality text output.
  22.    If someone wants an integration of TrueType with AmigaOS bullet.library
  23.    like outline font system, should consider using ttf.library. This library
  24.    opens TrueType font by itself and renders high quality glyphs directly
  25.    into any RastPort.
  26.  
  27.    FREETYPE2 BASED
  28.  
  29.    The render engine of the library is based on FreeType2 project
  30.    (http://www.freetype.org). This version of ttrender.library uses 2.0.9
  31.    FreeType build.
  32.  
  33.    REQUIREMENTS
  34.  
  35.    - OS 3.0+.
  36.    - 68020 or better processor.
  37.    - for antialiased output graphics board with at least 15-bit screenmode
  38.      and RTG system: CyberGraphX 3.x+ or Picasso96 2.x+.
  39.  
  40.    FEATURES
  41.  
  42.    The library expands FreeType functionality making usage of TrueType fonts
  43.    easy and comfortable. Below you can find key features:
  44.  
  45.    - renders whole strings (not single glyphs) with kerning.
  46.    - antialiasing to any (not neccesarily uniform color) background.
  47.    - system compatible output to any (including planar) RastPort.
  48.    - supports JAM1. JAM2, INVERSVID, COMPLEMENT RastPort modes.
  49.    - supports 8-bit to Unicode mapping with "ENV:ttfcodepage" table
  50.      compatible with ttf.library.
  51.    - allows for direct 16-bit Unicode string rendering.
  52.    - easy to use, taglist based API almost identical to graphics.library
  53.      font API.
  54.    - efficient system-wide glyph cache system.
  55.  
  56.    CACHE SYSTEM
  57.  
  58.    The library uses my own (not that experimental FreeType one) cache system
  59.    speeding up strings rendering alot. The cache is system-wide, it means it
  60.    is common to every application using ttrender.library. Only used glyphs of
  61.    given font face are cached. If the library encounters cache miss, missing
  62.    glyph is loaded and rasterized on the fly. Cache system is totally
  63.    transparent to the library user, so there are no cache functions in the
  64.    library API. Cache uses one single Exec memory pool avoiding memory
  65.    fragmentation.
  66.  
  67. ttrender.library/font_database                 ttrender.library/font_database
  68.  
  69.    GENERAL INFORMATION
  70.  
  71.    'ttengine.database' is a plain text file (placed in 'ENV:' directory)
  72.    containing informations about TrueType fonts available in the system.
  73.    There is no tool (yet) to automatically generate it, the database have to
  74.    be written by hand. Every line contains one keyword followed by parameter
  75.    value. Name and value can be separated by space(s) or equality sign,
  76.    exactly the same as shell command parameters (to say more - database is
  77.    parsed by the same ReadArgs() system call as shell command parameters
  78.    are). Parameter values containing spaces should be quoted. Here are some
  79.    examples:
  80.  
  81.    FAMILY Tahoma
  82.    FAMILY=Times
  83.    FAMILY = "Times New Roman"
  84.    FAMILY "Weird Font"
  85.  
  86.    KEYWORDS
  87.  
  88.    FAMILY - defines the name used for font opening. All variants of the font
  89.    (italic, bold, black, heavy, light, demi etc.) will have the same family
  90.    name. Family names (and aliases described below) are case insensitive.
  91.  
  92.    ALIAS - defines another name for the same family. It generally has three
  93.    purposes:
  94.  
  95.    1. Similar names for the same font, like "Times", "TimesNewRoman" and
  96.    "Times New Roman".
  97.  
  98.    2. One replacement font for some very similar ones, for example
  99.    "Helvetica" and "Switzerland" can be aliased to "Arial".
  100.  
  101.    3. Generic names like "default", "serif", "sans-serif", "monospaced". An
  102.    application can request generic name without specific family name, or
  103.    generic font can be used as a fallback if given name can't be found in
  104.    the database. For example you can alias "monospaced" to "Courier", and an
  105.    application (be it CSS compatible HTML viewer) can request
  106.    'LucidaConsole, monospaced'. If there is no LucidaConsole font in the
  107.    system, Courier will be used. The same way you can alias any font to any
  108.    other, for example Times to Arial, this makes not much sense however.
  109.    'default' font can be used as a last resort.
  110.  
  111.    FILE - defines single TrueType font file and its attributes, which are:
  112.      FILE itself - defines a path to the font file. Font files can be placed
  113.        anywhere in the filesystem(s). There is no default value for the
  114.        attribute, it must be given explicitly.
  115.      WEIGHT - defines font weight in Cascading Style Sheets manner, where 0
  116.        means the lightest and 999 means the heaviest weight. 400 is typical
  117.        value for normal weight, 700 for bold. Default value is 400 (normal).
  118.      STYLE - "regular" or "italic" for italic and oblique faces. Default
  119.        value is "regular".
  120.      SMOOTHSMALL - controls antialiasing of small sizes. Any sizes smaller or
  121.        equal to SMOOTHSMALL will be antialiased. Note: can be overriden by
  122.        application. Default value is 9.
  123.      SMOOTHBIG - controls antialiasing of big sizes. Any sizes bigger or
  124.        equal to SMOOTHBIG will be antialiased. Note: can be overriden by
  125.        application. Default value is 18.
  126.  
  127.      Every FILE is automatically added to the nearest FAMILY defined above
  128.      in the database file. Every ALIAS or FILE placed before the first
  129.      FAMILY is rejected quietly.
  130.  
  131.    COMMENTS
  132.  
  133.    You can place any full-line comments in the file starting a line with
  134.    hash or semicolon. End-line comments are not supported.
  135.  
  136. ttrender.library/TT_CloseFont                   ttrender.library/TT_CloseFont
  137.  
  138.    NAME
  139.        TT_CloseFont -- Closes TrueType font. (V4)
  140.  
  141.    SYNOPSIS
  142.        TT_CloseFont (font)
  143.                      A0
  144.  
  145.        VOID TT_CloseFont (APTR);
  146.  
  147.    FUNCTION
  148.        Closes font opened by TT_OpenFontA()
  149.  
  150.    INPUTS
  151.        font - the result of TT_OpenFontA(). Can be NULL, no action is taken
  152.            in the case.
  153.  
  154.    RESULT
  155.        none
  156.  
  157.    NOTES
  158.  
  159.    BUGS
  160.  
  161.    SEE ALSO
  162.        TT_OpenFontA()
  163.  
  164. ttrender.library/TT_GetAttrsA                   ttrender.library/TT_GetAttrsA
  165.  
  166.    NAME
  167.        TT_GetAttrsA -- Gets current font and render engine attributes (V4).
  168.  
  169.    SYNOPSIS
  170.        count = TT_GetAttrsA (rastport, taglist)
  171.                              A1        A0
  172.  
  173.        ULONG TT_GetAttrsA (struct RastPort*, struct TagItem*);
  174.  
  175.        count = TT_GetAttrs (rastport, Tag1, ...)
  176.  
  177.        ULONG TT_GetAttrs (struct RastPort*, Tag, ...);
  178.  
  179.    FUNCTION
  180.        Gets current font or render engine attributes for given RastPort. The
  181.        value of every attribute is written to an ULONG pointed by ti_Data
  182.        field of the TagItem. Here is a list of attributes:
  183.  
  184.        TT_Antialias - Current state of an antialias switch (on, off or
  185.           auto).
  186.  
  187.        TT_Ascender - This is a distance (in pixels) between the baseline
  188.          and top elements of the font (typically these elements are accents
  189.          of capital letters). NOTE: many shareware TT fonts have wrong ascen-
  190.          der value.
  191.  
  192.        TT_Descender - This is a distance (in pixels) between the baseline
  193.          and bottom elements of the font (typically in letters 'p', 'q', 'g'
  194.          etc.). NOTE: many shareware TT fonts have wrong descender value.
  195.          Descender value is typically negative (as bottom elements usually
  196.          are placed below the baseline).
  197.  
  198.        TT_FontName - full font name as found in the font file. Pointer to a
  199.          NULL-terminated string is written. This string is localized if the
  200.          font file contains names in different languages. Language
  201.          precedence is loaded from "Preferred languages" table of
  202.          locale.library.
  203.  
  204.        TT_FamilyName - font family name as found in the font file. Pointer
  205.          to a NULL-terminated string is written. This string is localized if
  206.          the font file contains names in different languages. Language
  207.          precedence is loaded from "Preferred languages" table of
  208.          locale.library.
  209.  
  210.        TT_SubfamilyName - font subfamily name (typically describing font
  211.          variant like "italic" or "bold") as found in the font file. Pointer
  212.          to a NULL-terminated string is written. This string is localized if
  213.          the font file contains names in different languages. Language
  214.          precedence is loaded from "Preferred languages" table of
  215.          locale.library.
  216.  
  217.        TT_Transparency - returns actual transparency setting.
  218.  
  219.        NOTE: TTFA_Ascender and TTFA_Descender are guarranted to fulfill
  220.        following formula: ascender - descender = font height.
  221.  
  222.    INPUTS
  223.        rastport - attributes associated with this RastPort will be returned.
  224.        taglist - the list of attributes.
  225.  
  226.    RESULT
  227.        counter - the count of recognized tags.
  228.  
  229.    NOTES
  230.        Data returned are valid only until TT_CloseFont() call.
  231.  
  232.    BUGS
  233.  
  234.    SEE ALSO
  235.        TT_OpenFontA(), TT_SetAttrsA()
  236.  
  237. ttrender.library/TT_OpenFontA                   ttrender.library/TT_OpenFontA
  238.  
  239.    NAME
  240.        TT_OpenFontA -- Opens TrueType font. (V4)
  241.  
  242.    SYNOPSIS
  243.        font = TT_OpenFontA (taglist)
  244.                                A0
  245.  
  246.        APTR TT_OpenFontA (struct TagItem*);
  247.  
  248.        font = TT_OpenFont (Tag1, ...)
  249.  
  250.        APTR TT_OpenFont (Tag, ...);
  251.  
  252.    FUNCTION
  253.        Opens a TrueType font preparing it to use with any RastPort. Font may
  254.        be specified directly as a path to "*.ttf" file, or indirectly via
  255.        set of attributes, database search will be performed for this set and
  256.        best matching font will be opened. It is graphics.library OpenFont()
  257.        counterpart but taglist is used instead TextAttr structure.
  258.  
  259.    INPUTS
  260.        taglist - a list of tags containing requested font attributes.
  261.               Following tags are recognized:
  262.          TT_FontFile - this tag is a pointer to string containing a full
  263.               path to TrueType font file to be opened. This tag allows for
  264.               overriding database search and match. That means
  265.               TT_FamilyTable, TT_FontStyle and TT_FontWeight are ignored if
  266.               TT_FontFile is specified. Useful for opening application
  267.               specific fonts, containing for example musical notes or some
  268.               other kind of symbols. This tag has no default value.
  269.          TT_FamilyTable - NULL-terminated table of pointers to font family
  270.               names from the most desired to the last resort fallback. It is
  271.               intended for easy implementing things like HTML 'FONT FACE'
  272.               attribute. You can use real family names here, as well as
  273.               generic names: 'serif', 'sans-serif', 'monospaced', 'cursive',
  274.               'fantasy', and 'default', especially useful as a fallbacks.
  275.               Family names are case insensitive.
  276.               The default value for the tag is {"default", NULL};
  277.          TT_FontSize - font size in pixels defined as the distance between
  278.               baselines of two following text lines. The default value for
  279.               this tag is 14 pixels.
  280.          TT_FontStyle - there are two styles defined:
  281.               TT_FontStyle_Regular (default),
  282.               TT_FontStyle_Italic.
  283.          TT_FontWeight - defined with Cascading Style Sheets manner as a
  284.               number from 0 (the lightest face) to 999 (the heaviest face).
  285.               You can use TT_FontWeight_Normal (equal to 400) and
  286.               TT_FontWeight_Bold (equal to 700) shortcuts.
  287.               TT_FontWeight_Normal is the default value.
  288.  
  289.    RESULT
  290.        success - font pointer (for use with TT_SetFont() and TT_CloseFont())
  291.                  if the font has been opened successfully, NULL
  292.                  otherwise. This function can fail for four reasons:
  293.                  1. There is no matching face in the database (NOTE: even
  294.                     'default' can fail if not defined in the database!)
  295.                  2. File not found or malformed.
  296.                  3. Zero font size.
  297.                  4. No memory for requested (too big?) size.
  298.  
  299.    NOTES
  300.  
  301.    BUGS
  302.  
  303.    SEE ALSO
  304.        TT_SetFont(), TT_CloseFont(), font_database
  305.  
  306. ttrender.library/TT_SetAttrsA                   ttrender.library/TT_SetAttrsA
  307.  
  308.    NAME
  309.        TT_SetAttrsA -- Sets rendering engine and font attributes. (V4)
  310.  
  311.    SYNOPSIS
  312.        count = TT_SetAttrsA (rastport, taglist)
  313.                              A1        A0
  314.  
  315.        ULONG TT_SetAttrsA (struct RastPort*, struct TagItem*);
  316.  
  317.        count = TT_SetAttrs (rastport, Tag1, ...)
  318.  
  319.        ULONG TT_SetAttrs (struct RastPort*, Tag, ...);
  320.  
  321.    FUNCTION
  322.        Sets render engine settings for given RastPort. Every following
  323.        TrutType render and metrics calls for this RastPort will use these
  324.        settings. Here is a list of attributes:
  325.  
  326.        TT_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
  327.          number to RGB color value.
  328.  
  329.        TT_Screen - (struct Screen*) - useful shortcut for TTA_ColorMap,
  330.          automatically sets screen ColorMap.
  331.  
  332.        TT_Window - (struct Window*) - useful shortcut for TTA_ColorMap,
  333.          automatically sets window ColorMap.
  334.  
  335.        TT_Antialias - (BOOL) - controls antialiasing (on, off or
  336.          automatic):
  337.          TTA_Antialias_Off - turns antialias off
  338.          TTA_Antialias_On - turns antialias on
  339.          TTA_Antialias_Auto (default) - antialias state depends on font
  340.            size. Typically sizes of 9 or less pixels are antialiased, sizes
  341.            from 10 to 19 pixels are not antialiased, sizes of 20 of more
  342.            pixels are antialiased. These settings can be changed in the font
  343.            database separately for every font face.
  344.  
  345.        TT_Encoding - selects font encoding table to be used:
  346.          TT_Encoding_Default - loads encoding table from "ENV:ttfcodepage"
  347.            file, compatible with ttf.library. If no such file is found,
  348.            ISO-8859-1 encoding (Amiga default) is used.
  349.          TT_Encoding_Unicode - strings are interpreted as tables of 16-bit
  350.            Unicode characters.
  351.          TT_Encoding_ISO8859_1 - ISO-8859-1 (Western Europe).
  352.          TT_Encoding_ISO8859_2 - ISO-8859-2 (Eastern and Central Europe).
  353.  
  354.        TT_Transparency - Allows for rendering transparent text (the
  355.          background shines through the text). 0 value means no transparency
  356.          (this is the default), 255 is maximum transparency.
  357.  
  358.        TT_ScaleX - a floating point (IEEE single precision) horizontal scale
  359.          factor. Its absolute value will be limited to <0.01, 100> range. It
  360.          may be negative (it means horizontal mirror around starting pen
  361.          position, string will be rendered to the left).
  362.  
  363.        TT_ScaleY - a floating point (IEEE single precision) vertical scale
  364.          factor. Its absolute value will be limited to <0.01, 100> range. It
  365.          may be negative (it means vertical mirror around the baseline,
  366.          string will be rendered mostly under the baseline).
  367.  
  368.    INPUTS
  369.        rastport - attributes will be set for this RastPort.
  370.        taglist - the list of attributes.
  371.  
  372.    RESULT
  373.        counter - the count of recognized tags.
  374.  
  375.    NOTES
  376.  
  377.    BUGS
  378.  
  379.    SEE ALSO
  380.        TT_OpenFontA(), TT_Text(), TT_GetAttrs()
  381.  
  382. ttrender.library/TT_SetFont                       ttrender.library/TT_SetFont
  383.  
  384.    NAME
  385.        TT_SetFont -- Sets TrueType font for a RastPort. (V4)
  386.  
  387.    SYNOPSIS
  388.        TT_SetFont (rastport, font)
  389.                    A1        A0
  390.  
  391.        BOOL TT_SetFont (struct RastPort*, APTR);
  392.  
  393.    FUNCTION
  394.        Sets a font previously opened with TT_OpenFontA() for use with given
  395.        RastPort. All further calls of text rendering or metrics function for
  396.        this RastPort will use font set.
  397.  
  398.    INPUTS
  399.        rastport - The font will be set for this RastPort.
  400.        font - Pointer returned by TT_OpenFontA(). May be NULL, function
  401.            returns immediately in the case.
  402.  
  403.    RESULT
  404.        TRUE if success, false otherwise.
  405.  
  406.    EXAMPLE
  407.        /* use two fonts to render in one RastPort */
  408.  
  409.        APTR times, arial;
  410.  
  411.        times = TT_OpenFont(
  412.           TT_FamilyTable, (ULONG){"Times", "serif", "default", NULL},
  413.           TT_FontSize, 26,
  414.        TAG_END);
  415.  
  416.        arial = TT_OpenFont(
  417.           TT_FamilyTable, (ULONG){"Arial", "sans-serif", "default", NULL},
  418.           TT_FontSize, 22,
  419.           TT_FontWeight, TT_FontWeight_Bold,
  420.        TAG_END);
  421.  
  422.        if (times && arial)
  423.          {
  424.            SetAPen(win->RPort, 1);
  425.            SetDrMd(win->RPort, JAM1);
  426.            Move(win->RPort, 100, 100);
  427.            TT_SetAttrs(win->RPort, TTA_Window, win, TAG_END);
  428.  
  429.            if (TT_SetFont(win->RPort, times))
  430.              TT_Text(win->RPort, "Times 26 points", 15);
  431.            if (TT_SetFont(win->RPort, arial))
  432.              TT_Text(win->RPort, "Arial 22 points", 15);
  433.          }
  434.        if (arial) TT_CloseFont(arial);
  435.        if (times) TT_CloseFont(times);
  436.  
  437.    NOTES
  438.      Function can fail returning FALSE if:
  439.      1. RastPort pointer is NULL.
  440.      2. Font pointer is NULL.
  441.      3. Font pointer is not found on opened fonts list (it means the pointer
  442.         was not obtained as a result of TT_OpenFontA() call).
  443.      4. Memory allocation during environment creation fails.
  444.  
  445.    BUGS
  446.  
  447.    SEE ALSO
  448.        TT_OpenFontA(), TT_SetAttrsA(), TT_CloseFont()
  449.  
  450. ttrender.library/TT_Text                             ttrender.library/TT_Text
  451.  
  452.    NAME
  453.        TT_Text -- Renders string into RastPort. (V4)
  454.  
  455.    SYNOPSIS
  456.        TT_Text (rastport, string, count)
  457.                 A1        A0      D0
  458.  
  459.        VOID TT_Text (struct RastPort*, APTR, ULONG);
  460.  
  461.    FUNCTION
  462.        Renders the string using current ttrender.library settings, and
  463.        current RastPort settings (pen, drawmode). String is rendered at
  464.        current RastPort (x, y) position, where 'y' means position of font
  465.        baseline. String is converted to Unicode according to
  466.        current (set by TT_SetAttrs()) encoding table.
  467.  
  468.    INPUTS
  469.        rastport - Target RastPort for rendering.
  470.        string - String to render to (need not to be NULL terminated).
  471.        count - How many characters to render (note that NULL code will
  472.            be rendered as well).
  473.  
  474.    RESULT
  475.        none
  476.  
  477.    EXAMPLE
  478.        /* write a text with pen 1 and transp. background at (100, 100) */
  479.        /* rendering is done to a system window                         */
  480.  
  481.        SetAPen(win->RPort, 1);
  482.        SetDrMd(win->RPort, JAM1);
  483.        Move(win->RPort, 100, 100);
  484.        TT_SetAttrs(win->RPort, TTA_Window, win, TAG_END);
  485.        TT_Text(win->RPort, "some text", 9);
  486.  
  487.    NOTES
  488.  
  489.    BUGS
  490.  
  491.    SEE ALSO
  492.        TT_OpenFontA(), TT_SetAttrsA()
  493.  
  494. ttrender.library/TT_TextExtent                 ttrender.library/TT_TextExtent
  495.  
  496.    NAME
  497.        TT_TextExtent -- Determine raster extent of text data. (V4)
  498.  
  499.    SYNOPSIS
  500.        TT_TextExtent (rastport, text, count, extent)
  501.                       A1        A0    D0:16  A2
  502.  
  503.        VOID TT_TextExtent (struct RastPort*, APTR, WORD,
  504.            struct TextExtent*);
  505.  
  506.    FUNCTION
  507.        Computes dimensions and coordinates of smallest rectangle containing
  508.        on the whole given text rendered with current settings. TextExtent
  509.        structure fields have following meaning:
  510.  
  511.        te_Width - Horizontal advance of RastPort pen position. The same as
  512.            TT_TextLength() call result.
  513.        te_Height - Just current font height.
  514.        te_Extent.MinX - The horizontal distance from text start point to the
  515.            leftmost pixel rendered. May be negative, it means that some
  516.            pixels will be plotted before the start point.
  517.        te_Extent.MaxX - The horizontal distance from text start point to the
  518.            rightmost pixel rendered.
  519.        te_Extent.MinY - The vertical distance from text start point to the
  520.            topmost pixel rendered. Always negative, do not neccesarily equal
  521.            to -TTFA_Ascender.
  522.        te_Extent.MaxY - The vertical distance from text start point to the
  523.            lowermost pixel rendered. Typically positive if anything is to be
  524.            drawn below the baseline.
  525.  
  526.    INPUTS
  527.        rastport - this rastport settings (font, size, style etc.) will be
  528.            used for calculations.
  529.        text - a string (not neccesarily NULL-terminated) to compute the
  530.            rectangle for.
  531.        count - length of the string in characters.
  532.        extent - pointer to TextExtent structure - it will be filled with
  533.            data.
  534.  
  535.    RESULT
  536.        No retrurn value. TextExtent structure is filled with data.
  537.  
  538.    NOTES
  539.        This function is almost identical to graphics.library/TextExtent().
  540.        It even receives parameters in the same registers.
  541.  
  542.        Do not assume neither horizontal extents sum up to te_Width, nor
  543.        vertical ones sum up to font height.
  544.  
  545.    BUGS
  546.  
  547.    SEE ALSO
  548.        TT_OpenFontA(), graphics.library/TextExtent()
  549.  
  550. ttrender.library/TT_TextFit                       ttrender.library/TT_TextFit
  551.  
  552.    NAME
  553.        TT_TextFit -- Count characters that will fit in a given extent. (V4)
  554.  
  555.    SYNOPSIS
  556.        characters = TT_TextFit (rastport, string, count, extent,
  557.                                 A1        A0      D0:16  A2
  558.            constr_extent, direction, width, height)
  559.            A3             D1         D2     D3
  560.  
  561.        ULONG TT_TextFit (struct RastPort*, APTR, UWORD, struct TextExtent*,
  562.            struct TextExtent*, WORD, UWORD, UWORD);
  563.  
  564.    FUNCTION
  565.        Computes how many characters of given NULL-terminated string rendered
  566.        with current settings will fit into given extent. Also calculates an
  567.        extent for this fitting part of the string. Function can fit from the
  568.        beginning of the string to the right, or from the end of the string
  569.        to the left. If 'constr_extent' is non NULL, string is fitted only
  570.        against it, constraining 'width' and 'height' are ignored.
  571.  
  572.    INPUTS
  573.        rastport - calculations will be performed using this rastport
  574.            settings (font, size, styles etc.).
  575.        string - A string (not neccesarily NULL-terminated) to fit.
  576.        count - string lenght in characters.
  577.        extent - Pointer to TextExtent structure - it will be filled with
  578.            dimensions of fitted part of the string. May be filled with all
  579.            zeros if no fit is possible at all (e.g. height is to small).
  580.        constr_extent - Pointer to already filled TextExtent structure. Part
  581.            of the string will fit into this extent. It is not modified by
  582.            function. May be NULL, 'width' and 'height' will be used as
  583.            constraints.
  584.        direction - When equal to 1 string will be fitted starting from it's
  585.            beginning to the rigth. When equal to -1, string will be fitted
  586.            starting from it's end to the left.
  587.        width - If 'constr_extent' is NULL, the string width will be compared
  588.            with this parameter. Ignored otherwise.
  589.        height - If 'constr_extent' is NULL, the string height will be
  590.            compared with this parameter. Ignored otherwise.
  591.  
  592.    RESULT
  593.        characters - the length of fitting string part. May be zero if no fit
  594.            found.
  595.  
  596.    NOTES
  597.        This function is almost identical to graphics.library/TextFit().
  598.        It even receives parameters in the same registers.
  599.  
  600.        Do not assume neither horizontal extents sum up to te_Width, nor
  601.        vertical ones sum up to font height (in returned extent).
  602.  
  603.    BUGS
  604.  
  605.    SEE ALSO
  606.        TT_OpenFontA(), graphics.library/TextFit()
  607.  
  608. ttrender.library/TT_TextLength                 ttrender.library/TT_TextLength
  609.  
  610.    NAME
  611.        TT_TextLength -- Gets string length in pixels (V4).
  612.  
  613.    SYNOPSIS
  614.        length = TT_TextLength(rastport, string, count)
  615.                               A1        A0      D0
  616.  
  617.        ULONG TT_TextLength (struct RastPort*, APTR, ULONG);
  618.  
  619.    FUNCTION
  620.        Calculates the pixel width of given string written with current font.
  621.        Takes kerning into account. String will be mapped to Unicode using
  622.        current encoding.
  623.  
  624.    INPUTS
  625.        rastport - render engine and font settings for this RastPort will be
  626.            used for calculations.
  627.        string - the length of this string will be calculated.
  628.        count - the string lenght in characters.
  629.  
  630.    RESULT
  631.        length - the length of the string in pixels.
  632.  
  633.    NOTES
  634.  
  635.    BUGS
  636.  
  637.    SEE ALSO
  638.        TT_Text(), TT_OpenFontA()
  639.  
  640.